GitHub Action入门指南

作为github的new ass，一般日常使用就是pull，push，拉点别人代码看看，CI之类的很少用，GitHub 把抓取代码、运行测试、登录远程服务器，发布到第三方服务等这些操作称为 actions。

操作在不同项目里面是类似的，GitHub 允许开发者把操作写成独立的脚本文件，存放到代码仓库，使得其他开发者可以引用。整个持续集成过程，成了一个 actions 的组合。

在 GithHub 市场里，可以直接拉别人提交的 actions ,或者 awesome actions 里也有好东西

基础

workflow （工作流程）：持续集成一次运行的过程，就是一个 workflow。每个 Workflow 最多可以执行 72 小时,创建 YAML 文件来创建 Workflow 配置。

job （任务）：一个 workflow 由一个或多个 jobs 构成，含义是一次持续集成的运行，可以完成多个任务。每个 Workflow 中的 job 最多可以执行 6 个小时

step（步骤）：每个 job 由多个 step 构成，一步步完成。

action （动作）：每个 step 可以依次执行一个或多个命令（action）。在一个存储库的所有 Action 中，一个小时最多可以执行 1000 个 API 请求

workflow

workflow 文件就是 actions 的配置文件，用 yaml 格式的 .yml 书写，存放在代码仓库的.github/workflows目录，一个库可以有多个 workflow 文件。

字段介绍如下：

name：Workflow 的名称，会显示在 Action 页，忽略该字段，则默认为相对根目录的工作流文件路径。

on：就是 Actions 触发器，可以绑定多个事件。也支持外部事件，定时运行等。同时，可以指定限定分支/标签的事件触发响应。也支持使用活动类型。更多直接查官方文档

on: push
on: [push,pull_request,release]
on:
  push:
    branches:    
      - 'main'
on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches-ignore:    
      - 'mona/octocat'
      - 'releases/**-alpha'
on:
  label:
    types: [created, edited]

jobs：一个 Workflow 由一个或多个 jobs 构成，含义是一次持续集成的运行，可以完成多个任务。

通过 job 的 id 定义一个 job，每个 job 必须要有一个 id。大致如下：

• name 指定 job 的名称，在 GitHub 中会显示
• runs-on 指定运行环境，必填。
• steps 指定运行步骤，可以包含多步步骤，可以指定多种字段：name，env，run，if，uses，shell 等，更多参看官方文档。
• env 指定环境，在整个工作流程或者某一个步骤中也可以设定，具体看需求和控制范围而定。
• needs 指定 job 的依赖。
• if 可以用条件来组织 job 的运行

jobs:
  first_job_id:
    name: first_job_name
    runs-on: ubuntu-18.04
  second_job_id:
    name: second_job_name
    runs-on: ubuntu-latest
    needs: first_jod_id
    steps:

steps：指定运行步骤，可以包含多步步骤，可以指定多种字段：name，env，run，if，uses，shell 等，更多参看官方文档。可以运行命令行命令，环境配置命令，另一端 action等。在自己的运行器环境内运行，可访问工作空间、文件系统，也就是说，step 之间不会保留对环境变量的修改。

• name
• env 配置环境
• run 执行命令
• if 条件控制
• uses 可以直接引用其他的 actions
• shell 指定 shell 类型

环境矩阵

如果需要多个编译环境，可以写个矩阵

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    os: [ubuntu-16.04, ubuntu-18.04]
    node: [8, 10]
steps:
  ......

实战

hexo自动部署为例

这里参照了 Hexo Action 给出的实例。

准备工作

• 在源文件库下的 .github 文件夹下，创建 workflows 文件夹，在内添加 deploy.yml ，内容见下一小节

• 创建新密钥：

  ssh-keygen -t rsa -f ~/.ssh/id_rsa_x -C "yourmail@xxx.com"
  cat ~/.ssh/id_rsa_x.pub
  # This is the public key
  cat ~/.ssh/id_rsa_x
  # This is the private key

• 部署密钥，将公钥放到网页托管仓库（即xx.github.io）的 Setting / Deploykey 内，私钥要复制到网页代码源仓库（即私有库）的 Setting / Secrets / Actions 内，在 Action secrets 内 New 一个 reposity secret，名字是 DEPLOY_KEY （其他名字也可以，在 deploy.yml 内相应修改即可。）复制包括 BEGIN OPENSSH PRIVATE KEY 和 END OPENSSH PRIVATE KEY。

这几步主要是配置 GitHub 的工作环境，因为类似本地环境，所以同样需要一对公钥 + 私钥用于仓库间的加密传输。当 GitHub Action 执行 hexo g -d 时，用私钥 DEPLOY_KEY 加密，GitHub 用网站文件仓库的公钥进行验证。整个流程就完成了。

yml代码

name: Deploy

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    name: A job to deploy blog.
    steps:
    - name: Checkout
      uses: actions/checkout@v1
      with:
        submodules: true # Checkout private submodules(themes or something else).
    
    # Caching dependencies to speed up workflows. (GitHub will remove any cache entries that have not been accessed in over 7 days.)
    - name: Cache node modules
      uses: actions/cache@v1
      id: cache
      with:
        path: node_modules
        key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
        restore-keys: |
          ${{ runner.os }}-node-
    - name: Install Dependencies
      if: steps.cache.outputs.cache-hit != 'true'
      run: npm ci
    
    # Deploy hexo blog website.
    - name: Deploy
      id: deploy
      uses: sma11black/hexo-action@v1.0.3
      with:
        deploy_key: ${{ secrets.DEPLOY_KEY }}
        user_name: your github username  # (or delete this input setting to use bot account)
        user_email: your github useremail  # (or delete this input setting to use bot account)
        commit_msg: ${{ github.event.head_commit.message }}  # (or delete this input setting to use hexo default settings)
    # Use the output from the `deploy` step(use for test action)
    - name: Get the output
      run: |
        echo "${{ steps.deploy.outputs.notify }}"

代码解析

• step1是获取源码
• step2是缓存压缩 node_modules，避免每次下载一次，加快部署速度，每次部署时，解压使用，七天内没有使用才会删除。
• step3安装相关依赖，也即执行 npm install ，不过 npm ci 用于自动化环境、测试平台、持续集成和部署。跳过某些面向用户的功能，比常规的 npm 安装快。也比常规安装更严格，可以帮助捕获由大多数 npm 用户的增量安装的本地环境引起的错误或不一致。
• step4部署 hexo，这里引用了 hexo action ，需要配置的是放在源代码仓库的私钥名称，用户名、邮箱和反馈信息
• 最后是 action 的输出打印。

错误

一般来说配置好是没有问题的，如果提示 denied to deploy key，一般就是公钥放错地方了。

还有就是站点配置文件的 repo 写错了，一般来说本地能部署上传，action 的配置也不会有什么错，有错就是 action 没写对。

参考

github-docs-about-custom-actions

Events that trigger workflows

Marketplace GitHub actions

awesome actions

GitHub Actions Market: Checkout

Hexo action